Sprite 1984

home *** CD-ROM | disk | FTP | other *** search

/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib.fmt / c / Pfs.man < prev next >

Wrap

Text File | 1990-11-13 | 27.5 KB | 663 lines

Pfs C Library Procedures Pfs _________________________________________________________________ NNAAMMEE Pfs_Open, Pfs_OpenConnection, Pfs_SetHandler, Pfs_PassFile, Pfs_Close - Package for servicing pseudo-file-systems. SSYYNNOOPPSSIISS ##iinncclluuddee <<ppddeevv..hh>> Pfs_Token PPffss__OOppeenn(_p_r_e_f_i_x, _r_o_o_t_I_D_P_t_r, _p_f_s_S_e_r_v_i_c_e, _c_l_i_e_n_t_D_a_t_a) Pdev_Stream * PPffss__OOppeennCCoonnnneeccttiioonn(_p_f_s_T_o_k_e_n, _f_i_l_e_I_D_P_t_r, _r_e_q_B_u_f_S_i_z_e, _r_e_a_d_B_u_f_- _S_i_z_e, _r_e_a_d_B_u_f, _s_e_l_e_c_t_B_i_t_s, _p_d_e_v_S_e_r_v_i_c_e) int (* PPffss__SSeettHHaannddlleerr(_p_f_s_T_o_k_e_n, _o_p_e_r_a_t_i_o_n, _h_a_n_d_l_e_r))() int PPffss__PPaassssFFiillee(_p_f_s_T_o_k_e_n, _s_t_r_e_a_m_I_D) void PPffss__CClloossee(_p_f_s_T_o_k_e_n) AARRGGUUMMEENNTTSS char *_p_r_e_f_i_x (in) File name prefix of the pseudo-file- system. Fs_FileID *_r_o_o_t_I_D_P_t_r (in) The server-defined ID of the root. Pfs_CallBacks *_p_f_s_S_e_r_v_i_c_e (in) Set of name service call-back pro- cedures. ClientData _c_l_i_e_n_t_D_a_t_a (in) User-defined data passed to service call-backs. Pfs_Token _p_f_s_T_o_k_e_n (in) Return value of PPffss__OOppeenn. Fs_FileID *_f_i_l_e_I_D_P_t_r (in) Server's identifier for file in pseudo- file-system. int _r_e_q_B_u_f_S_i_z_e (in) Preferred size for the request buffer. int _r_e_a_d_B_u_f_S_i_z_e (in) Size of read buffer. Zero means no read buffering. char *_r_e_a_d_B_u_f (in) Optional read Sprite v.1.0 Printed: November 12, 1990 1 Pfs C Library Procedures Pfs buffer, or NULL. int _s_e_l_e_c_t_B_i_t_s (in) FFSS__RREEAADDAABBLLEE, FFSS__WWRRIITTAABBLLEE, FFSS__EEXXCCEEPPTTIIOONN Pdev_CallBacks *_p_d_e_v_S_e_r_v_i_c_e (in) Set of pseudo-device service call-back procedures. int _s_t_r_e_a_m_I_D (in) A regular open file descriptor returned from ooppeenn. _________________________________________________________________ PPffss__OOppeenn PPffss__OOppeenn declares a server process for a pseudo-file-system and installs a set of service procedures for it. The ser- vice procedures are called when client processes do file naming operations on the pseudo-file-system, i.e. ooppeenn, ssttaatt, uunnlliinnkk, mmkkddiirr, rrmmddiirr, rreennaammee, and lliinnkk. As a side effect of opening a file in the pseudo-file-system the server can set up a pseudo-device connection for the open file. Thus the server can completely implement file system access to the pseudo-file-system. The _p_r_e_f_i_x argument indicates what part of the global file system hierarchy is controlled by the pseudo-file-system server. This prefix can be arbitrarily nested in the hierarchy but there must be a remote link that corresponds to it. (The command llnn --rr _p_r_e_f_i_x creates a remote link for the prefix.) The existence of the remote link ensures that the kernel's lookup algorithm will automatically find the pseudo-file-system server. The pseudo-file-system is visi- ble across the network as well. The _r_o_o_t_I_D_P_t_r defines the file ID for the root of the pseudo-file-system. This ID will be presented as the pprree-- ffiixxIIDD for pathnames that begin at the root (prefix) of the pseudo-file-system. The file ID has the following format. The server can define the file ID to fit its own needs. However, the special type value of -1 is reserved to indi- cate an invalid file ID. typedef struct { int type; int serverID; int major; int minor; } Fs_FileID; The _p_f_s_S_e_r_v_i_c_e procedures are described in detail below. The _c_l_i_e_n_t_D_a_t_a argument is passed to all the naming service Sprite v.1.0 Printed: November 12, 1990 2 Pfs C Library Procedures Pfs procedures. It is ordinarily used to get to the state of the pseudo-file-system. The return value of PPffss__OOppeenn is a token for the pseudo- file-system, which must be used in calls to PPffss__OOppeennCCoonnnneeccttiioonn, PPffss__PPaassssFFiillee, PPffss__SSeettHHaannddlleerr, and PPffss__CClloossee. If a pseudo-file-system couldn't be opened, then NULL is returned and ppffss__EErrrroorrMMssgg contains a string describ- ing the problem. The Pfs package uses the facilities of FFss__DDiissppaattcchh in order to keep track of the streams associated with the pseudo- file-system and ensure that Pfs is notified whenever those streams become readable. In order to use Pfs, you must also use FFss__DDiissppaattcchh. PPffss__OOppeennCCoonnnneeccttiioonn PPffss__OOppeennCCoonnnneeccttiioonn is used to create open file connections to the pseudo-file-system indicated by _p_f_s_T_o_k_e_n. Open file connections can only be made during an ooppeenn call-back. The open file connection is the same as a connection to a pseudo-device with the addition of two new requests to han- dle ffssttaatt, ffcchhmmoodd, and ffcchhoowwnn. The details of using the pseudo-device call-backs are given in the PPddeevv man page. The _f_i_l_e_I_D_P_t_r is a server-defined identifier for the open file. The server can set the file ID fields to any values that make sense to it. However, by convention a type of -1 indicates an invalid fileID. This special case may occur when handling the rreennaammee and hhaarrddLLiinnkk call-backs. Note that the file IDs for directories in the pseudo-file-system may be presented back to the server as a pprreeffiixxIIDD that indicates the starting point of the lookup operation. Thus a process can have a current directory inside the pseudo-file-system and name files relative to that directory. The _p_d_e_v_S_e_r_v_i_c_e parameter is a set of pseudo-device call- backs. The use of these call-backs is described in detail in the PPddeevv man page. The _r_e_q_B_u_f_S_i_z_e parameter indicates the preferred size of the request buffer associated with the pseudo-device connection. This size determines how many requests can be bufferred before the kernel has to wait on the server. A minimum size is enforced by the library, so zero can be passed to get the default size (about 1 Kbyte). The _r_e_a_d_B_u_f_S_i_z_e and _r_e_a_d_B_u_f parameters indicate the size and location of an optional read buffer. No buffering is indi- cated by a zero read buffer size. See the library PPddeevv and device ppddeevv man pages for more details on using a read buffer. Sprite v.1.0 Printed: November 12, 1990 3 Pfs C Library Procedures Pfs PPffss__PPaassssFFiillee PPffss__PPaassssFFiillee is used to pass the open file descriptor of a regular file back to a client in response to an open request. If this is done then the pseudo-file-system server sees no further requests concerning this open file; the file is handled in the regular way the by kernel. PPffss__PPaassssFFiillee exists, but the kernel doesn't support it, yet. PPffss__CClloossee PPffss__CClloossee is used to end pseudo-file-system service. This closes the naming stream to the kernel and frees up any dynamically allocated storage. After this call _p_f_s_T_o_k_e_n should not be used. PPffss__PPaassssFFiillee exists, but the kernel doesn't support it, yet. NNAAMMEE SSEERRVVIICCEE PPRROOCCEEDDUURREESS The callbacks are given to PPffss__OOppeenn as a record of pro- cedures: typedef struct { int (*open)(); /* PFS_OPEN */ int (*getAttr)();/* PFS_GET_ATTR */ int (*setAttr)();/* PFS_SET_ATTR */ int (*makeDevice)();/* PFS_MAKE_DEVICE */ int (*makeDir)();/* PFS_MAKE_DIR */ int (*remove)();/* PFS_REMOVE */ int (*removeDir)();/* PFS_REMOVE_DIR */ int (*rename)();/* PFS_RENAME */ int (*hardLink)();/* PFS_HARD_LINK */ int (*symLink)();/* PFS_SYM_LINK */ } Pfs_CallBacks; Any of the elements can be NULL to indicate that the opera- tion should be handled by a default handler that is a no-op procedure that returns a file-not-found error. The _s_e_r_v_i_c_e parameter to PPffss__OOppeenn itself can also be NULL to indicate default handling for all operations. This is only useful during initial test. The global variable ppffss__TTrraaccee can be set to a non-zero value to generate printfs to stderr when each service procedure (default or user-supplied) is invoked. All the name service procedures have a similar calling sequence that includes a relative pathname, a record con- taining input parameters, and a buffer for _p_a_t_h_n_a_m_e _r_e_d_i_r_e_c_- _t_i_o_n. (The rreennaammee and hhaarrddlliinnkk procedures have slighly dif- ferent calling sequences because they handle two pathnames.) The pathname is relative to a prefix indicated by a _p_r_e_f_i_x_I_D in the input parameters. This ID is either for the root as defined by the _r_o_o_t_I_D_P_t_r argument to PPffss__OOppeenn, or for some Sprite v.1.0 Printed: November 12, 1990 4 Pfs C Library Procedures Pfs directory who's ID was defined by PPffss__OOppeennCCoonnnneeccttiioonn when the directory was entered by a client process. The service procedures should return 0 to mean success, oth- erwise they should return a suitable errno value. There are no other return results. Open file connections are created as a side effect using PPffss__OOppeennCCoonnnneeccttiioonn. It is possible that the pathname may leave the pseudo-file- system during any lookup operation. This happens with remote links, symbolic links back to the root, or with enough ``..'' components to take the pathname out the top of the pseudo-file-system. In this case the pseudo-file-system server should return the remaining, or new, pathname instead of attempting to follow it itself. The return code EERREEMMOOTTEE is used to indicate this situation, and the _r_e_d_i_r_e_c_t_P_t_r argument is used to return the new name: typedef struct FsRedirectInfo { int prefixLength; char fileName[FS_MAX_PATH_NAME_LENGTH]; } FsRedirectInfo; If the lookup hits a symbolic link to the root the server should expand the link and return the new absolute pathname in this buffer. A remote link is like a symbolic link, except it indicates a nested prefix and its contents are the prefix itself. Expanding it will result in a new absolute pathname. The length of the prefix that is embedded in the absolute path should be returned in the pprreeffiixxLLeennggtthh field. With regular symbolic links this field should be zero. If the server hits a ``..'' component that leaves its root it should place the remaining pathname, including the offending ``..'' component, into the buffer. The prefix length is again zero in this case. ooppeenn int (*service->open)(clientData, name, openArgsPtr, redirectPtr) ClientData clientData;/* Passed into Pfs_Open */ char *name; /* Relative pathname */ Fs_OpenArgs *openArgsPtr;/* Identifies prefix and caller */ FsRedirectInfo *redirectPtr;/* Return - new pathname and prefix info if * name leaves the pseudo-file-system */ The open service procedure is invoked in response to an ooppeenn system call by a client process. The _c_l_i_e_n_t_D_a_t_a argument is the value passed into PPffss__OOppeenn and is generally used to get back to the state kept for the pseudo-file-system. The _n_a_m_e is a relative pathname that begins at the prefix indicated by *_o_p_e_n_A_r_g_s_P_t_r. The FFssOOppeennAArrggss structure identifies the root of the pseudo-file-system, the prefix or starting Sprite v.1.0 Printed: November 12, 1990 5 Pfs C Library Procedures Pfs directory of the pathname, and the identity of the calling process: typedef struct { Fs_FileID prefixID; /* File ID from prefix handle */ Fs_FileID rootID; /* File ID of root. */ int useFlags; /* Flags defined in fs.h */ int permissions; /* Permission bits for created files. Already * reflects per-process permission mask */ int type; /* Used to contrain open to a specific type */ int clientID; /* Host ID of client doing the open */ Fs_UserIDs id; /* User and group IDs */ } FsOpenArgs; The pprreeffiixxIIDD is either the fileID of the root of the pseudo-file-system, or the fileID of some directory in the pseudo-file-system that has been previously opened. The uusseeFFllaaggss is an or'd combination of flags defined in <fs.h> that include FFSS__RREEAADD, FFSS__WWRRIITTEE, and FFSS__EEXXEECCUUTTEE. The ppeerrmmiiss-- ssiioonnss define the file mode when creating a file. File crea- tion is indicated by the FFSS__CCRREEAATTEE usage flag. The ttyyppee is used to constrain the open to a particular kind of file. Possible values are FFSS__FFIILLEE, which means any type will do, FFSS__DDIIRREECCTTOORRYY when changing the current directory, and FFSS__SSYYMMBBOOLLIICC__LLIINNKK when reading links. IMPORTANT: PPffss__OOppeennCCoonnnneeccttiioonn and PPffss__PPaassssFFiillee can only be called during the servicing of an open request. If they are called (successfully) by the open call-back it must return 0, never a non-zero error status. ggeettAAttttrr int (*service->getAttr)(clientData, name, openArgsPtr, attrPtr, redirectInfoPtr) ClientData clientData;/* Passed into Pfs_Open */ char *name; /* Relative pathname */ FsOpenArgs *openArgsPtr;/* Bundled arguments */ Fs_Attributes *attrPtr;/* Return - attributes of the file */ FsRedirectInfo *redirectInfoPtr;/* Used when name leaves our domain */ This call-back is made to get the attributes of a file in the pseudo-file-system given its pathname. The arguments are similar to those of the ooppeenn call-back. The _a_t_t_r_P_t_r argument is used to return the attributes. sseettAAttttrr int (*service->setAttr)(clientData, name, openArgsPtr, flags, attrPtr, redirectInfoPtr) ClientData clientData;/* Passed into Pfs_Open */ char *name; /* Relative pathname */ Sprite v.1.0 Printed: November 12, 1990 6 Pfs C Library Procedures Pfs FsOpenArgs *openArgsPtr;/* Bundled arguments */ int flags; /* Specifies which attrs to set */ Fs_Attributes *attrPtr;/* New attributes of the file */ FsRedirectInfo *redirectInfoPtr;/* Used when name leaves our domain */ This call-back is made to set certain attributes of a file in the pseudo-file-system given its pathname. The arguments are similar to those of the ooppeenn call-back. Additionally, the _f_l_a_g_s argument indicates which attributes are to be set, and the _a_t_t_r_P_t_r argument specifies their new values. The _f_l_a_g_s are an or'd combination of FFSS__SSEETT__TTIIMMEESS, FFSS__SSEETT__MMOODDEE, FFSS__SSEETT__OOWWNNEERR, FFSS__SSEETT__FFIILLEE__TTYYPPEE, FFSS__SSEETT__DDEEVVIICCEE. mmaakkeeDDeevviiccee int (*service->makeDevice)(clientData, name, makeDevArgsPtr, redirectInfoPtr) ClientData clientData;/* Passed into Pfs_Open */ char *name; /* Relative pathname */ FsMakeDeviceArgs *makeDevArgsPtr;/* Bundled arguments */ FsRedirectInfo *redirectInfoPtr;/* Used when name leaves our domain */ This call-back is made to create a special device file in the pseudo-file-system. The FFssMMaakkeeDDeevviicceeAArrggss are similar to the FFssOOppeennAArrggss with some addition information about the dev- ice: typedef struct { Fs_FileID prefixID; /* FileID of the prefix */ Fs_FileID rootID; /* FileID of the root */ Fs_Device device; /* Device attributes */ int permissions; /* Permissions already reflect per-process mask */ Fs_UserIDs id; /* Identifies calling process */ int clientID; /* Identifies host of calling process */ } FsMakeDeviceArgs; mmaakkeeDDiirr int (*service->makeDir)(clientData, name, openArgsPtr, redirectInfoPtr) ClientData clientData;/* Passed into Pfs_Open */ char *name; /* Relative pathname */ FsOpenArgs *openArgsPtr;/* Bundled arguments */ FsRedirectInfo *redirectInfoPtr;/* Used when name leaves our domain */ This call-back is made to create a directory. The arguments are similar to those of the ooppeenn call-back. rreemmoovvee int (*service->remove)(clientData, name, lookupArgsPtr, redirectInfoPtr) ClientData clientData;/* Passed into Pfs_Open */ char *name; /* Relative pathname */ FsLookupArgs *lookupArgsPtr;/* Bundled arguments */ Sprite v.1.0 Printed: November 12, 1990 7 Pfs C Library Procedures Pfs FsRedirectInfo *redirectInfoPtr;/* Used when name leaves our domain */ This call-back is made to remove a file in the pseudo-file- system. FFssLLooookkuuppAArrggss are a simplified sub-set of FFssOO-- ppeennAArrggss: typedef struct { Fs_FileID prefixID; /* FileID of the prefix */ Fs_FileID rootID; /* FileID of the root */ int useFlags; /* not used */ Fs_UserIDs id; /* User and group IDs of calling process */ int clientID; /* Host ID of calling process */ } FsLookupArgs; rreemmoovveeDDiirr int (*service->removeDir)(clientData, name, lookupArgsPtr, redirectInfoPtr) ClientData clientData;/* Passed into Pfs_Open */ char *name; /* Relative pathname */ FsLookupArgs *lookupArgsPtr;/* Bundled arguments */ FsRedirectInfo *redirectInfoPtr;/* Used when name leaves our domain */ This call-back is made to remove a directory in the pseudo- file-system. The server should check against removing non- empty directories. The arguments are the same as for rreemmoovvee. rreennaammee int (*service->rename)(clientData, srcName, dstName, twoNameArgsPtr, redirect2InfoPtr) ClientData clientData; /* Passed into Pfs_Open */ char *srcName; /* Original name */ char *dstName; /* New name */ Fs2PathParams *twoNameArgsPtr;/* Lookup args plus prefixID2 */ Fs2PathRedirectInfo *redirect2InfoPtr;/* Used when name leaves our domain */ This call-back is made to change the name of a file in the pseudo-file-system. The arguments are bundled into the FFss22PPaatthhPPaarraammss structure: typedef struct Fs2PathParams { FsLookupArgs lookup; /* Regular lookup parameters */ Fs_FileID prefixID2; /* Prefix of second pathname */ } Fs2PathParams; It is possible that the second pathname is not a part of the pseudo-file-system. The Sprite kernel still calls out to the pseudo-file-system in this case because the first path- name might be redirected out of the pseudo-file-system. If the second prefixID does not belong to the pseudo-file- system that is indicated by a ttyyppee value of -1. If the Sprite v.1.0 Printed: November 12, 1990 8 Pfs C Library Procedures Pfs first pathname remains in the pseudo-file-system but the second prefixID is not in the pseudo-file-system then the error EEXXDDEEVV should be returned. If either of the pathnames gets redirected, or an error occurs during pathname interpretation, the FFss22PPaatthhRReeddiirreeccttIInnffoo structure is used to return more information: typedef struct { int name1ErrorP;/* TRUE if redirection or other error applies * to the first pathname, FALSE if the error * applies to second pathname, or no error */ int prefixLength;/* The length of the prefix embedded in * fileName. This is used when a server hits * a remote link and has to return a new file * name plus an indication of a new prefix. */ char fileName[FS_MAX_PATH_NAME_LENGTH]; /* The new file name. Returned * from the server when its lookup is about * to leave its domain. */ } Fs2PathRedirectInfo; hhaarrddLLiinnkk int (*service->hardLink)(clientData, srcName, dstName, twoNameArgsPtr, redirect2InfoPtr) ClientData clientData; /* Passed into Pfs_Open */ char *srcName; /* Original name */ char *dstName; /* New name */ Fs2PathParams *twoNameArgsPtr;/* Lookup args plus prefixID2 */ Fs2PathRedirectInfo *redirect2InfoPtr;/* Used when name leaves our domain */ This call-back is used to create a hard link between two files in the pseudo-file-system. The arguments are the same as those for rreennaammee, and the same comments about pathname redirection apply. ssyymmLLiinnkk int (*service->symLink)(clientData, linkName, value, openArgsPtr, redirectInfoPtr) ClientData clientData; /* returned from Pfs_Open */ char *linkName; /* SymLink file name */ char *value; /* Symlink value */ FsOpenArgs *openArgsPtr; /* Open arguments */ FsRedirectInfo *redirectInfoPtr;/* Used when srcName leaves our domain */ This call-back is used to create a symbolic link in the pseudo-file-system. The arguments are similar to those for ooppeenn, except there are two pathnames. Pathname redirection is only possible on the _l_i_n_k_N_a_m_e. The _v_a_l_u_e pathname is simply used as the value of the link regardless of its loca- tion in the system. (This is not currently used. Symbolic links are created instead by opening a file of type Sprite v.1.0 Printed: November 12, 1990 9 Pfs C Library Procedures Pfs FS_SYMBOLIC_LINK and writing the link value into it. This will change, although it currently works in NFS.) The ttyyppee field in the open args is used differentiate between a regular symbolic link and a remote link. A remote link is a circular symbolic link with a different file descriptor type than a symbolic link. Remote links are used in native Sprite file systems to indicate a nested prefix that is stored elsewhere. Bumping into a remote link causes a pathname redirection just like hitting a symbolic link back to the root. Additionally, however, the redirection information also includes the length of the prefix that is embedded into the returned pathname. SSEEEE AALLSSOO pfs (devices), Pdev, Swap_Buffer KKEEYYWWOORRDDSS pseudo-file-system Sprite v.1.0 Printed: November 12, 1990 10